/*
 * $Id: ether.h,v 1.9 2005-12-09 06:50:31 bacon Exp $
 */

#ifndef _XP_NET_ETHER_H_
#define _XP_NET_ETHER_H_

#include <xp/types.h>
#include <xp/macros.h>

/*
 * MACRO: XP_ETHER_LEN
 *   Number of bytes in an ethernet address
 */
#define XP_ETHER_LEN 6

#ifdef __cplusplus
extern "C" {
#endif

/*
 * FUNCTION: xp_ether_aton
 *   Converts an ethernet address string to binary data
 *
 * PARAMETERS:
 *   str - [in] ethernet address in the standard colon-hexadecimal notation.
 *   hw - [out] pointer to the binary ethernet address buffer
 *
 * RETURNS:
 *   0 on success, -1 on failure
 * 
 * DESCRIPTION:
 *   <xp_ether_aton> converts a null-terminated ethernet address in the 
 *   standard colon-hexadecimal notation as in 11:22:33:AA:BB:CC. It accepts
 *   both lower-case and upper-case characters for A to F.
 * 
 * SEE ALSO: 
 *   <xp_ether_xaton>
 */
int xp_ether_aton (
	const xp_char_t* str, xp_byte_t hw[XP_ETHER_LEN]);

/*
 * FUNCTION: xp_ether_xaton
 *   Converts a length-bounded ethernet address string to binary data
 *
 * PARAMETERS:
 *   str - [in] ethernet address in the standard colon-hexadecimal notation.
 *   len - [in] length of *str*
 *   hw - [out] pointer to the binary ethernet address buffer
 *
 * RETURNS:
 *   0 on success, -1 on failure
 *
 * DESCRIPTION:
 *   <xp_ether_xaton> is similar to <xp_ether_aton>, except that the ethernet
 *   string is length-bounded instead of being null-terminated.
 *
 * SEE ALSO: 
 *   <xp_ether_aton>
 */
int xp_ether_xaton (
	const xp_char_t* str, xp_size_t len, xp_byte_t hw[XP_ETHER_LEN]);

/*
 * FUNCTION: xp_ether_ntoa
 *   Converts the binary ethernet address to a string
 *
 * PARAMETERS:
 *   hw - [in] binary ethernet address
 *   buf - [out] buffer to hold converted string
 *   size - [in] maximum number of characters *buf* can hold
 * 
 * RETURNS: 
 *   Length of the resulting string 
 */
xp_size_t xp_ether_ntoa (
	const xp_byte_t hw[XP_ETHER_LEN], xp_char_t* buf, xp_size_t size);

#ifdef __cplusplus
}
#endif

#endif
